home *** CD-ROM | disk | FTP | other *** search
/ Ultra Pack / UltraComputing Partner Applications.iso / SunLabs / tclTK / src / tcl7.4 / README < prev    next >
Encoding:
Text File  |  1995-06-30  |  13.2 KB  |  296 lines
  1. Tcl
  2.  
  3. by John Ousterhout
  4. john.ousterhout@eng.sun.com
  5.  
  6. @(#) README 1.14 95/06/30 11:18:26
  7.  
  8. 1. Introduction
  9. ---------------
  10.  
  11. This directory contains the sources and documentation for Tcl, an
  12. embeddable scripting language.  The information here corresponds
  13. to release 7.4.  This release contains many bug fixes and a few new
  14. features; it should be backwards compatible with Tcl 7.3 except for
  15. one change related to Tcl_AppInit (see below for details).
  16.  
  17. 2. Documentation
  18. ----------------
  19.  
  20. The best way to get started with Tcl is to read one of the introductory
  21. books on Tcl:
  22.  
  23.     Tcl and the Tk Toolkit, by John Ousterhout,
  24.     Addison-Wesley, 1994, ISBN 0-201-63337-X
  25.  
  26.     Practical Programming in Tcl and Tk, by Brent Welch,
  27.     Prentice-Hall, 1995, ISBN 0-13-182007-9
  28.  
  29. The "doc" subdirectory in this release contains a complete set of reference
  30. manual entries for Tcl.  Files with extension ".1" are for programs (for
  31. example, tclsh.1); files with extension ".3" are for C library procedures;
  32. and files with extension ".n" describe Tcl commands.  The file "doc/Tcl.n"
  33. gives a quick summary of the Tcl language syntax.  To print any of the man
  34. pages, cd to the "doc" directory and invoke your favorite variant of
  35. troff using the normal -man macros, for example
  36.  
  37.         ditroff -man Tcl.n
  38.  
  39. to print Tcl.n.  If Tcl has been installed correctly and your "man"
  40. program supports it, you should be able to access the Tcl manual entries
  41. using the normal "man" mechanisms, such as
  42.  
  43.         man Tcl
  44.  
  45. 3. Compiling and installing Tcl
  46. -------------------------------
  47.  
  48. This release should compile and run either "out of the box" or with
  49. trivial changes on any UNIX-like system that approximates POSIX, BSD,
  50. or System V.  I know that it runs on workstations from Sun, H-P, and
  51. DEC.  To compile Tcl, do the following:
  52.  
  53.     (a) Check for patches.  Look in the FTP directory from which you
  54.         retrieved the base distribution and see if there are files with
  55.     names like tcl7.4p1.patch, tcl7.4p2patch, etc.  These files may
  56.     also have .Z extensions to indicate compression.  If you find
  57.     any patch files, apply them to the source directory in order
  58.     from "p1" up.  To apply an uncompressed patch file such as
  59.     tcl7.4p1.patch, invoke a shell command like the following from
  60.     the directory containing this file:
  61.         patch -p < tcl7.4p1.patch
  62.     If the patch file is compressed, invoke a command like the following:
  63.         zcat tcl7.4p2.patch.Z | patch -p
  64.  
  65.     (b) Type "./configure" in this directory.  This runs a configuration
  66.     script created by GNU autoconf, which configures Tcl for your
  67.     system and creates a Makefile.  The configure script allows you
  68.     to customize the Tcl configuration for your site;  for details on
  69.     how you can do this, check out the autoconf documenation (not
  70.     included here).
  71.  
  72.     (c) Type "make".  This will create a library archive called "libtcl.a"
  73.     and an interpreter application called "tclsh" that allows you to type
  74.     Tcl commands interactively or execute script files.
  75.  
  76.     (d) If the make fails then you'll have to personalize the Makefile
  77.         for your site or possibly modify the distribution in other ways.
  78.     First check the file "porting.notes" to see if there are hints
  79.     for compiling on your system.  If you need to modify Makefile,
  80.     there are comments at the beginning of it that describe the things
  81.     you might want to change and how to change them.
  82.  
  83.     (e) Type "make install" to install Tcl binaries and script files in
  84.         standard places.  You'll need write permission on the installation
  85.     directoryies to do this.  The installation directories are
  86.     determined by the "configure" script and may be specified with
  87.     the --prefix and --exec_prefix options to "configure".  See the
  88.     Makefile for information on what directories were chosen; you
  89.     can override these choices by modifying the "prefix" and
  90.     "exec_prefix" variables in the Makefile.
  91.  
  92.     (f) At this point you can play with Tcl by invoking the "tclsh"
  93.     program and typing Tcl commands.  However, if you haven't installed
  94.     Tcl then you'll first need to set your TCL_LIBRARY variable to
  95.     hold the full path name of the "library" subdirectory.  Note
  96.     that the installed versions of tclsh and libtcl.a have a version
  97.     number in their names, such as "tclsh7.4" or "libtcl7.4.a";
  98.     to use the installed versions, either specify the version number
  99.     or create a symbolic link (e.g. from "tclsh" to "tclsh7.4").
  100.  
  101. If you have trouble compiling Tcl, I'd suggest looking at the file
  102. "porting.notes".  It contains information that people have sent me about
  103. changes they had to make to compile Tcl in various environments.  Or,
  104. check out the following Web URL:
  105.     http://www.sunlabs.com/cgi-bin/tcl/info.4.0
  106. This is an on-line database of porting information.  I make no guarantees
  107. that this information is accurate, complete, or up-to-date, but you may
  108. find it useful.  If you get Tcl running on a new configuration, I'd be
  109. happy to receive new information to add to "porting.notes".  You can also
  110. make a new entry into the on-line Web database.  I'm also interested in
  111. hearing how to change the configuration setup so that Tcl compiles out
  112. of the box on more platforms.
  113.  
  114. 4. Test suite
  115. -------------
  116.  
  117. There is a relatively complete test suite for all of the Tcl core in
  118. the subdirectory "tests".  To use it just type "make test" in this
  119. directory.  You should then see a printout of the test files processed.
  120. If any errors occur, you'll see a much more substantial printout for
  121. each error.  See the README file in the "tests" directory for more
  122. information on the test suite.
  123.  
  124. The Tcl test suite is very sensitive to proper implementation of
  125. ANSI C library procedures such as sprintf and sscanf.  If the test
  126. suite generates errors, most likely they are due to non-conformance
  127. of your system's ANSI C library;  such problems are unlikely to
  128. affect any real applications so it's probably safe to ignore them.
  129.  
  130. 5. Additional release information
  131. ---------------------------------
  132.  
  133. There is now an official home for Tcl and Tk on the Web at the following
  134. URL:
  135.     http://www.smli.com/research/tcl
  136. These Web pages include release updates, reports on bug fixes and
  137. porting issues, and pointers to many other Tcl/Tk Web pages at other
  138. sites.  Check them out!
  139.  
  140. 6. Summary of changes in Tcl 7.4
  141. --------------------------------
  142.  
  143. Tcl 7.4 is a minor release.  There are many bug fixes (most of them
  144. minor), but only a few new features and just one potential
  145. incompatibility.  For complete information on what has changed, see
  146. the file "changes".
  147.  
  148. The one incompatible change is that Tcl no longer provides a "main"
  149. procedure by default.  What used to be "main" is now called "Tcl_Main",
  150. and each application needs to provide a "main" that calls "Tcl_Main".
  151. Typically this is done in the tclAppInit.c file;  see the tclAppInit.c
  152. file in the distribution for an example.
  153.  
  154. Here is a summary of the new features in Tcl 7.4:
  155.  
  156.     1. Added new "subst" command for making $ and [] substitutions on
  157.     an strings.
  158.  
  159.     2. The "array" command has several new features:
  160.     - "get" and "set" commands for conversion between arrays
  161.       and strings.
  162.     - "exists" command for checking for array element existence.
  163.     - "names" and "size" commands now treat a non-existent array
  164.       the same as an empty one.
  165.     - "names" takes an optional pattern argument.
  166.  
  167.     3. "lindex", "linsert", "lrange", and "lreplace" all accept
  168.     "end" as an index.
  169.  
  170.     4. Expressions support unary "+".
  171.  
  172.     5. The "string" command has new "wordstart" and "wordend" options.
  173.  
  174.     6. Tcl now exports the procedures Tcl_RegExpCompile, Tcl_RegExpExec,
  175.     and Tcl_RegExpRange for C-level access to pattern matching.
  176.  
  177.     7. When an error occurs while creating a pipeline with "open", it
  178.     is returned immediately as the result of the "open" rather than being
  179.     delayed until the "close" command.
  180.  
  181.     8. "regsub" now returns a count of the number of matches and
  182.     replacements, rather than 0/1.
  183.  
  184.     9. Added mechanism for tracking renames of commands.  See the
  185.     new procedure Tcl_GetCommandName.
  186.  
  187.     10. Added tcl_library variable (whose value is now returned by the
  188.     "info library" command).  This allows the application to change the
  189.     location of the Tcl libraries.  Also added tcl_patchLevel and
  190.     tcl_version variables for use instead of "info patchlevel" and
  191.     "info version" (but the "info" commands still exist).
  192.  
  193.     11. The installed versions of tclsh and libtcl.a now have version
  194.     numbers appended to them:  tclsh7.4 and libtcl7.4.a.
  195.  
  196.     12. Added option pattern argument to "parray" library procedure.
  197.  
  198.     13. Added TCL_EVAL_GLOBAL flag to Tcl_RecordAndEval.
  199.  
  200. 7. Tcl newsgroup
  201. -----------------
  202.  
  203. There is a network news group "comp.lang.tcl" intended for the exchange
  204. of information about Tcl, Tk, and related applications.  Feel free to use
  205. the newsgroup both for general information questions and for bug reports.
  206. I read the newsgroup and will attempt to fix bugs and problems reported
  207. to it.
  208.  
  209. 8. Tcl contributed archive
  210. --------------------------
  211.  
  212. Many people have created exciting packages and applications based on Tcl
  213. and made them freely available to the Tcl community.  An archive of these
  214. contributions is kept on the machine ftp.aud.alcatel.com.  You can
  215. access the archive using anonymous FTP;  the Tcl contributed archive is
  216. in the directory "/tcl".  The archive also contains several FAQ ("frequently
  217. asked questions") documents that provide solutions to problems commonly
  218. encountered by TCL newcomers.
  219.  
  220. 9. Support and bug fixes
  221. ------------------------
  222.  
  223. We're very interested in receiving bug reports and suggestions for
  224. improvements.  I suggest sending this information to the comp.lang.tcl
  225. newsgroup rather than to me.  We'll see anything on comp.lang.tcl,
  226. and in addition someone else who reads comp.lang.tcl may be able to
  227. offer a solution.  Bugs usually get fixed in 1-3 weeks, but enhancements
  228. may take a while and may not happen at all unless there is widespread
  229. support for them (I'm trying to slow the rate at which Tcl turns into
  230. a kitchen sink).  It's almost impossible to make incompatible changes
  231. to Tcl at this point.
  232.  
  233. When reporting bugs, please provide a short tclsh script that we can
  234. use to reproduce the bug.  Make sure that the script runs with a
  235. bare-bones tclsh and doesn't depend on any extensions or other
  236. programs, particularly those that exist only  at your site.  Also,
  237. please include three additional pieces of information with the
  238. script:
  239.     (a) how do we use the script to make the problem happen (e.g.
  240.     what things do we click on, in what order)?
  241.     (b) what happens when you do these things (presumably this is
  242.         undesirable)?
  243.     (c) what did you expect to happen instead?
  244.  
  245. The Tcl community is too large for us to provide much individual
  246. support for users.  If you need help I suggest that you post questions
  247. to comp.lang.tcl.  We read the newsgroup and will attempt to answer
  248. esoteric questions for which no-one else is likely to know the answer.
  249. In addition, Tcl support and training are available commercially from
  250. NeoSoft (info@neosoft.com), Computerized Processes Unlimited
  251. (gwl@cpu.com), and Data Kinetics (education@dkl.com).
  252.  
  253. 9. Tcl release organization
  254. ---------------------------
  255.  
  256. Each Tcl release is identified by two numbers separated by a dot, e.g.
  257. 6.7 or 7.0.  If a new release contains changes that are likely to break
  258. existing C code or Tcl scripts then the major release number increments
  259. and the minor number resets to zero: 6.0, 7.0, etc.  If a new release
  260. contains only bug fixes and compatible changes, then the minor number
  261. increments without changing the major number, e.g. 7.1, 7.2, etc.  If
  262. you have C code or Tcl scripts that work with release X.Y, then they
  263. should also work with any release X.Z as long as Z > Y.
  264.  
  265. Beta releases have an additional suffix of the form bx.  For example,
  266. Tcl 7.0b1 is the first beta release of Tcl version 7.0, Tcl 7.0b2 is
  267. the second beta release, and so on.  A beta release is an initial
  268. version of a new release, used to fix bugs and bad features before
  269. declaring the release stable.  Each new release will be preceded by
  270. one or more beta releases.  We hope that lots of people will try out
  271. the beta releases and report problems back to me.  We'll make new beta
  272. releases to fix the problems, until eventually there is a beta release
  273. that appears to be stable.  Once this occurs we'll remove the beta
  274. suffix so that the last beta release becomes the official release.
  275.  
  276. If a new release contains incompatibilities (e.g. 7.0) then we can't
  277. promise to maintain compatibility among its beta releases.  For example,
  278. release 7.0b2 may not be backward compatible with 7.0b1.  we'll try
  279. to minimize incompatibilities between beta releases, but if a major
  280. problem turns up then we'll fix it even if it introduces an
  281. incompatibility.  Once the official release is made then there won't
  282. be any more incompatibilities until the next release with a new major
  283. version number.
  284.  
  285. 10. Compiling on non-UNIX systems
  286. --------------------------------
  287.  
  288. The Tcl features that depend on system calls peculiar to UNIX (stat,
  289. fork, exec, times, etc.) are now separate from the main body of Tcl,
  290. which only requires a few generic library procedures such as malloc
  291. and strcpy.  Thus it should be relatively easy to compile Tcl for
  292. non-UNIX machines such as MACs and DOS PC's, although a number of
  293. UNIX-specific commands will be absent (e.g.  exec, time, and glob).
  294. See the comments at the top of Makefile for information on how to
  295. compile without the UNIX features.
  296.